.TH std::optional::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::optional::swap \- std::optional::swap

.SH Synopsis
   void swap( optional& other ) noexcept(/* see below */);  \fI(since C++17)\fP
                                                            (constexpr since C++20)

   Swaps the contents with those of other.

     * If neither *this nor other contain a value, the function has no effect.
     * If only one of *this and other contains a value (let's call this object in and
       the other un), the contained value of un is direct-initialized from
       std::move(*in), followed by destruction of the contained value of in as if by
       in->T::~T(). After this call, in does not contain a value; un contains a value.
     * If both *this and other contain values, the contained values are exchanged by
       calling using std::swap; swap(**this, *other). T lvalues must satisfy Swappable.

   The program is ill-formed if std::is_move_constructible_v<T> is false.

.SH Parameters

   other - the optional object to exchange the contents with

.SH Return value

   \fI(none)\fP

.SH Exceptions

   noexcept specification:
   noexcept(std::is_nothrow_move_constructible_v<T> &&
            std::is_nothrow_swappable_v<T>)

   In the case of thrown exception, the states of the contained values of *this and
   other are determined by the exception safety guarantees of swap of type T or T's
   move constructor, whichever is called. For both *this and other, if the object
   contained a value, it is left containing a value, and the other way round.

.SH Example


// Run this code

 #include <iostream>
 #include <optional>
 #include <string>

 int main()
 {
     std::optional<std::string> opt1("First example text");
     std::optional<std::string> opt2("2nd text");

     enum Swap { Before, After };
     auto print_opts = [&](Swap e) {
         std::cout << (e == Before ? "Before swap:\\n" : "After swap:\\n");
         std::cout << "opt1 contains '" << opt1.value_or("") << "'\\n";
         std::cout << "opt2 contains '" << opt2.value_or("") << "'\\n";
         std::cout << (e == Before ? "---SWAP---\\n": "\\n");
     };

     print_opts(Before);
     opt1.swap(opt2);
     print_opts(After);

     // Swap with only 1 set
     opt1 = "Lorem ipsum dolor sit amet, consectetur tincidunt.";
     opt2.reset();

     print_opts(Before);
     opt1.swap(opt2);
     print_opts(After);
 }

.SH Output:

 Before swap:
 opt1 contains 'First example text'
 opt2 contains '2nd text'
 ---SWAP---
 After swap:
 opt1 contains '2nd text'
 opt2 contains 'First example text'

 Before swap:
 opt1 contains 'Lorem ipsum dolor sit amet, consectetur tincidunt.'
 opt2 contains ''
 ---SWAP---
 After swap:
 opt1 contains ''
 opt2 contains 'Lorem ipsum dolor sit amet, consectetur tincidunt.'

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR    Applied to              Behavior as published               Correct behavior
   P2231R1 C++20      swap was not constexpr while the required        made constexpr
                      operations can be constexpr in C++20

.SH See also

   std::swap(std::optional) specializes the std::swap algorithm
   \fI(C++17)\fP                  \fI(function template)\fP

.SH Category:
     * conditionally noexcept
